\section{Communications}
\label{sect:p2ml}

Here is a description of all the commands used between the WC and OSS.

% TEST
\subsection{TestCommand}
This command is just a test and does not do anything at all.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
name & The name of the User.\\
gubbins & A sort of Gubbin to use.\\
wotsit & Another really useful parameter.\\
size & The size of the gubbins(mm).\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
ID & The ID of the User.\\
thing & A thing assocaied with the gubbins.\\
doings & Another thing we need.\\
itemic & an item sort of thingy.\\
\end{tabular}


% FIND USER
\subsection{FindUser}
Locates a user by their \emph{name} field. 
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
name & The name of the User.\\
\end{tabular}

\subsubsection{Reply}
\begin{tabular}{lp{30em}}
ID & The ID of the User.\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No user with the specified name could be found.\\
\end{tabular}

% LIST USERS
\subsection{ListUsers}
Requests a list of users.
\subsubsection{Parameters}
None
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
Users & A list of user headers (see \ref{xml:user}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No users could be found in the database.\\
\end{tabular}

% LIST TAGS
\subsection{ListTags}
Requests a list of Tags.
\subsubsection{Parameters}
None
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
tags & A list of TAG headers (see \ref{xml:tag}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No Tags could be found in the database.\\
\end{tabular}

% LIST PROGS
\subsection{ListProgs}
Requests a list of Programs.
\subsubsection{Parameters}
None
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
tags & A list of program headers (see \ref{xml:prog}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No programs could be found in the database.\\
\end{tabular}

% LIST PROPOSALS
\subsection{ListProposals}
Requests a list of proposals belonging to the specified owner, which may be of type User, Program or TAG.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the owner.\\
type & The type of owner. One of {\bf USER}, {\bf PROG}, {\bf TAG}.\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
proposals & A list of Proposal headers (see \ref{xml:proposal}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No proposals could be found in the database belonging to the specified owner.\\
yyy & Unknown owner type.\\
\end{tabular}

% LIST GROUPS
\subsection{ListGroups}
Request a list of Groups belonging to a specified Proposal.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the proposal.\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
groups & A list of group headers (see \ref{xml:group}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No proposal with the specified ID could be found.\\
\end{tabular}

% GET GROUP
\subsection{GetGroup}
Requests a header for a specified group.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the group.\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
group & The group header (see \ref{xml:group}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No group with the specified ID could be found.\\
\end{tabular}

% GET GROUP HISTORY
\subsection{GetGroupHistory}
Requests a list of history items for a specified group.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the group.\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
history & A list of history items for the group (see \ref{xml:history}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & The group does not have a history.\\
\end{tabular}

% LIST OBS
\subsection{ListObs}
Requests a list of observation headers for a specified group.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the group.\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
observations & A list of observation headers (see \ref{xml:observation}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No group with the specified ID could be found.\\
\end{tabular}


% GET OBS
\subsection{GetObs}
Requests the headers for the specified observation.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the observation.\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
observation & The headers for the specified observation.(see \ref{xml:observation}).\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No observation with the specified ID could be found.\\
\end{tabular}

% LIST ACCOUNTS
\subsection{ListAccounts}
Requests a list of account headers for the specified proposal, user, tag or program.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the owner.\\
type & Type of owner. One of {\bf USER}, {\bf PROG}, {\bf TAG}, {\bf PROPOSAL}.
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
accounts & A list of account headers for the specified owner.\\
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
xxx & No owner of the specified type and ID could be found.\\
yyy & Unknown owner type.\\
\end{tabular}

% GET ACCOUNT
\subsection{GetAccount}
Requests the account headers for a specified account.
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
ID & The ID of the account.\\
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
\end{tabular}


%
% COMMAND DESCRIPTION TEMPLATE
%
\subsection{}
\subsubsection{Parameters}
\begin{tabular}{lp{30em}}
\end{tabular}
\subsubsection{Reply}
\begin{tabular}{lp{30em}}
\end{tabular}
\subsubsection{Errors}
\begin{tabular}{lp{30em}}
\end{tabular}

\section{XML}

Communication between the remote client(s) and the OSS server will be by an XML dialect known as Phase 2 Markup Language (P2ML). Each command will contain the following items:-

\begin{itemize}
\item An ID. This must be unique between clients and over time including reboots such as $<clientID>$@$<address>$:$<sequenceNo>$ e.g. cmm:TmcAdmin@150.204.240.123:55555
\item An action class. This determines the eoperation to be performed at the database. e.g. \emph{UpdateGroup}.
\item A number of parameters specific to the action class. These may be primitive values e.g. identifiers or may encapsulate details of complex object graphs such as observation specifications.
\end{itemize}

\begin{verbatim}
<p2ml:command id = "wc@150.204.240.123:1234567">
 <action class = "LockGroup">
 <param name = "groupID">
    645464646
 </param>
 <param name = "clientID">
    WCUser@TMC:john.smith
 </param>
</p2ml:command>
\end{verbatim}

The reply to a command which has completed successfuly should contain:-
\begin{itemize}
\item The ID of the original command.
\item A series of data parameters specific to the command's action class. These may be primitive values e.g. identifiers or may encapsulate details of complex object graphs such as observation specifications.
\end{itemize}

\begin{verbatim}
<p2ml:reply id = "wc@150.204.240.123:1234567">
 <data name = "key">
    8575757575
 </data>
</p2ml:reply>
\end{verbatim}

The reply to a command which has failed should contain:-
\begin{itemize}
\item The ID of the original command.
\item An error code selected from the set of valid codes (see \ref{errors}).
\item A message detailing the cause of the fault. This could contain substructure which can be parsed by a remote client.
\end{itemize}

\begin{verbatim}
<p2ml:error id = "wc@150.204.240.123:1234567">
 <code>758004</code> 
 <message>
   <text>The group is already locked</text>
   <user>jo.bloggs</user>
   <date>2005-12-18T12:45:08UTC</date>
   <client>nsoc@150.204.123.112</client>
 </message> 
</p2ml:error>
\end{verbatim}

Here is a big long example with structure within the request parameters.
\begin{verbatim}
<p2ml:command id = "wc@150.204.240.123:1234999">

 <action class = "UpdateObservation">

  <param name = "obsID">
    8575757
  </param>

  <param name = "obsHeader">

    <observation name = "obs-r4">

      <exposure>
        <time>300.0</time>
        <repeat>6</repeat>
      </exposure>

      <target>
        <targetID> 85858 </targetID>   
        <raOffset>  15.0 </raOffset>
        <decOffset> -3.5 </decOffset>
      </target>

      <instrument class = "ngat.phase2.CCDConfig">
        <filter wheel = "lower"> SDSS-B </filter>
        <filter wheel = "upper"> CLEAR  </filter>
        <bin>2</bin>
        <calibrate seq = "before"> TRUE  <calibrate>
        <calibrate seq = "after">  FALSE <calibrate>
      </instrument>

      <scope>
        <focusOffset>0.03</focusOffset>
        <autoguider use = "OPTIONAL"/>
        <rotator mode = "SKY" angle = "10.0"/>
      </scope>

      <mosaic pattern = "CROSS">
       <xOffset> 3.0 </xOffset>
       <yOffset> 0.2 </yOffset>
      </mosaic>      

    </observation>

  </param>

</p2ml:command>
\end{verbatim}

Here we give details of the XML used to describe the various phase2 objects when encapsulated in a P2ML command/reply xml wrapper. I wonder if we should be using JAXB or some other clever thing to do this for us !
